home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 14 / CU Amiga Magazine's Super CD-ROM 14 (1997)(EMAP Images)(GB)(Track 1 of 3)[!][issue 1997-09].iso / CUCD / Programming / XPK / Developer / Autodocs / xpkpreferences.doc < prev    next >
Encoding:
Text File  |  1997-04-01  |  7.9 KB  |  166 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkmaster.library/--general--
  4. xpkmaster.library/--replacements--
  5. xpkmaster.library/--semaphore--
  6.  
  7. xpkmaster.library/--general--                   xpkmaster.library/--general--
  8.  
  9.     THE PREFERENCES IDEA
  10.         In version 4 of xpkmaster.library a preferences system has been
  11.         added to support file type depending packing. The implementation in
  12.         master library is done by a semaphore mechanism (see below for this).
  13.         Some additional tools are provided to handle the preferences.
  14.         - XpkMaster      - a normal SYS:Prefs/ preferences program.
  15.         - XpkMasterPrefs - an IPrefs like support for the preferences.
  16.  
  17.     WHEN PREFERENCES ARE USED
  18.     The preferences are used, when no (XPK_Preferences, FALSE) is
  19.     passed. One of the Semaphore installing programs has to be
  20.     started before, as xpkmaster.library only calls the semaphore and
  21.     no files.
  22.     The preferences pack happens when you call XpkPack and the
  23.     XPK_PackMethod tag data contains any of the following:
  24.       1) 0
  25.       2) ""
  26.       3) "USER"
  27.  
  28.     THE PREFERENCES FORMAT
  29.         The preferences are normal IFF PREF files, with a PRHD chunk
  30.         containing information like the file version and XPKT and XPKM
  31.         chunks with settings relevant to xpk. The structure of these hunks
  32.         are defined in <xpk/xpkprefs.h> as struct XpkMainPrefs and struct
  33.         XpkTypePrefs. These seem to be the first chunks containing
  34.         pointers, therefore I will describe the format below.
  35.  
  36.     IFF POINTERS
  37.         In memory a pointer is a 32 bit variable holding the address of
  38.         another variable it refers to. A pointer of value 0 points to the
  39.         start of memory. The same system is used for pointers in xpk prefs
  40.         files. In the prefs files, ANY pointer refers relative to the first
  41.         byte after the size information of the current chunk. So saving of
  42.         a chunk goes following steps:
  43.         - allocate a area of memory to hold all data
  44.         - copy the main structure (either XpkTypePrefs or XpkMainPrefs) to
  45.           the start of this area
  46.         - copy all other data behind the main structure and set all
  47.           pointers to point to the new place in this area.
  48.         - now subtract the start address of the memory from all pointers
  49.         The last two steps can be done in one.
  50.         For examples how to do this, see the sources in Prefs directory of
  51.         xpk_Source.lha archive.
  52.         Loading needs following steps:
  53.         - load the file into a buffer of chunk size
  54.         - add address of memory area to all pointer values
  55.         - repeat this for all sub structures, you created the real address
  56.           a step before. (In XpkTypePrefs prefs are pointers to XpkTypeData
  57.           which point to strings --> 3 different levels to correct, each
  58.           after each other.)
  59.  
  60. xpkmaster.library/--replacements--         xpkmaster.library/--replacements--
  61.  
  62.     MAKING YOUR OWN PREFERENCES
  63.         The preferences structure of xpkmaster.library is very open. Only a
  64.         few fields of the semaphore (see below) are accessed by the master
  65.         library directly. The preference files will never be accessed by
  66.         the master library. So it is possible to replace the preferences
  67.         system completely with an totally different one (may be depending
  68.         on one of the file identifying libraries). You only have to make
  69.         a program to build a public semaphore with exact the same name as
  70.         the standard one and the same semaphore structure and set
  71.         following fields:
  72.     sem->xps_Version
  73.       Set to version of your structure (for future enhancements).
  74.     sem->xps_PrefsType
  75.       Any ULONG value defining your preferences type. Try to use a
  76.       value not used by another system.
  77.     sem->ps_PrefsData
  78.       Here you may store a pointer to private data. This data is not
  79.       read by xpkmaster.library.
  80.     sem->xps_MainPrefs
  81.       Pointer to default preferences. When this is set to zero,
  82.       internally defaults are used.
  83.     sem->xps_RecogSize
  84.       Size of the file buffer you need for finding the right packer.
  85.     sem->xps_RecogFunc
  86.       Pointer to the function scanning for the right packer. See below
  87.       for more information.
  88.     sem->xps_ProgressFunc
  89.       This is a normal progress hook function, which is called, when
  90.       the user selects XPK_ChunkReport. This function is not required.
  91.     sem->xps_MasterTask
  92.       This a pointer the the task structure of the semaphore installer.
  93.       The installer task has to quit, when it gets a SIGBREAKF_CTRL_C
  94.       signal!
  95.  
  96. xpkmaster.library/--semaphore--               xpkmaster.library/--semaphore--
  97.  
  98.     SEMAPHORE GENERAL
  99.         Semaphores are a way to allow multitasking friendly access to
  100.         public data structures. You get access following way:
  101.  
  102.   Forbid();
  103.   if((sem = (struct XpkPrefsSemaphore *) FindSemaphore(XPKPREFSSEMNAME)))
  104.     ObtainSemaphoreShared((struct SignalSemaphore *) sem);
  105.   Permit();
  106.  
  107.         Now you either own it, or it does not exist. Do not forget to check
  108.         if sem is zero after this piece of code. If not, you can READ all
  109.         documented fields of the semaphore now. (If you want to write, use
  110.         ObtainSemaphore() instead). There are some other methods for access.
  111.         See programming manuals for these.
  112.         
  113.         After work you have to free the semaphore by calling
  114.  
  115.   ReleaseSemaphore((struct SignalSemaphore *) sem);
  116.  
  117.     THE XPKMASTER PREFERENCES SEMAPHORE
  118.         The structure of this semaphore is described in xpk/xpkprefs.h. Most
  119.         of the fields are not accessed by xpkmaster.library. This semaphore
  120.         is public, so you may read all data of it, but because the stuff is
  121.         done by xpkmaster.library there should be no need to do so. Writing
  122.         to the semaphore is allowed too, but should never happen.
  123.         See xpk/xpkprefs.h to get conditions.
  124.  
  125.         The most important part of the semaphore are the fields
  126.         xps_RecogSize and xps_RecogFunc. xps_RecogSize is the size of the
  127.         buffer needed by xps_RecogFunc to find out the filetype.
  128.         xps_RecogFunc is a function to find out the filetype of a file and
  129.         to return the specific packer type for this file.
  130.  
  131.     THE RECOG FUNCTION
  132.         INPUTS
  133.         - A pointer to a buffer holding the beginning of the file is passed
  134.           in register A0.
  135.         - In register A1 the filename of the file is passed. This may be
  136.           zero, because in some cases xpkmaster.library does not have the
  137.           filename.
  138.     - In register A2 a filename is passed you may present user in own
  139.       requesters or in chunkhooks. When you do packing in the Recog
  140.       function then use XPK_FileName tag and pointer from A2 as data.
  141.         - In register D0 the size of buffer in A0 is passed. This should
  142.           equal xps_RecogSize or when the file is shorter be the file
  143.           length.
  144.     - In register D1 the complete file size is passed.
  145.         OUTPUT
  146.         - Register D0 passes a pointer to a struct XpkTypeData holding the
  147.           needed information for packing. If no information, return should
  148.           be zero.
  149.         - If return value equals -1 (0xFFFFFFFF), the function will be
  150.           called again with buffer size equal to file size. Do not return -1
  151.           when buffer size already equals file size.
  152.         - When 0 is returned the data form xps_MainPrefs or the internal
  153.           defaults are used.
  154.         NOTE
  155.         - The Recog function should take the filename only as additional
  156.           feature. If no filename is given the filename check cannot take
  157.           place (it is always true).
  158.         - For callers: The returned data is valid only as long as you
  159.           obtain the semaphore.
  160.         - When xpkmaster.library should free the XpkTypeData stuff, then
  161.           set the fields xtd_Memory and xtd_MemorySize. xpkmaster.library
  162.           calls then FreeMem(t->xtd_Memory, t->xtd_MemorySize);. The memory
  163.           must not point to the XpkTypeData structure!
  164.       This is useful, when the type is not in a list, but is created.
  165.       NOTE: The memory area may hold passwords or other data.
  166.